/*
 * Copyright (c) 2024 Huawei Device Co., Ltd.
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

#ifndef DRAWING_TEXT_FONT_DESCRIPTOR_H
#define DRAWING_TEXT_FONT_DESCRIPTOR_H

/**
 * @addtogroup Drawing
 * @{
 *
 * @brief Drawing模块提供包括2D图形渲染、文字绘制和图片显示等功能函数。\n
 * 本模块采用屏幕物理像素单位px。
 *
 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing
 *
 * @since 8
 * @version 1.0
 */

/**
 * @file drawing_text_font_descriptor.h
 *
 * @brief 定义了字体信息的相关接口，比如获取字体信息，查找指定字体等。
 *
 * @include native_drawing/drawing_text_font_descriptor.h
 * @library libnative_drawing.so
 * @kit ArkGraphics2D
 * @since 14
 * @version 1.0
 */

#include "drawing_text_typography.h"
#include "drawing_types.h"

#ifdef __cplusplus
extern "C" {
#endif

/**
 * @brief 字体类型的枚举。
 *
 * @since 14
 */
typedef enum {
    /** 所有字体类型。 */
    ALL = 1 << 0,
    /** 系统字体类型。 */
    GENERIC = 1 << 1,
    /** 风格字体类型 */
    STYLISH = 1 << 2,
    /** 用户已安装字体类型。 */
    INSTALLED = 1 << 3,
    /**
     * 自定义字体类型。
     * @since 18
     * */
    CUSTOMIZED = 1 << 4,
} OH_Drawing_SystemFontType;

/**
 * @brief 字体描述符属性的枚举。不同类型的字体描述符属性，请使用对应类型的接口获取属性。如字体描述符属性FULL_DESCRIPTOR_ATTR_I_WEIGHT为int类型，需使用{@link OH_Drawing_GetFontFullDescriptorAttributeInt}接口获取其属性值。
 *
 * @since 22
 */
typedef enum {
    /** 字体文件的路径，{@link OH_Drawing_String}类型。 */
    FULL_DESCRIPTOR_ATTR_S_PATH = 0,
    /** 唯一标识字体的名称，{@link OH_Drawing_String}类型。 */
    FULL_DESCRIPTOR_ATTR_S_POSTSCRIPT_NAME = 1,
    /** 字体的名称，{@link OH_Drawing_String}类型。 */
    FULL_DESCRIPTOR_ATTR_S_FULL_NAME = 2,
    /** 字体家族的名称，{@link OH_Drawing_String}类型。 */
    FULL_DESCRIPTOR_ATTR_S_FAMILY_NAME = 3,
    /** 子字体家族的名称，{@link OH_Drawing_String}类型。 */
    FULL_DESCRIPTOR_ATTR_S_SUB_FAMILY_NAME = 4,
    /** 字体的字重，int类型。 */
    FULL_DESCRIPTOR_ATTR_I_WEIGHT = 5,
    /** 字体的宽窄风格属性，int类型。 */
    FULL_DESCRIPTOR_ATTR_I_WIDTH = 6,
    /** 字体是否倾斜，int类型。1表示字体倾斜，0表示字体非倾斜。 */
    FULL_DESCRIPTOR_ATTR_I_ITALIC = 7,
    /** 字体是否紧凑，bool类型。true表示字体紧凑，false表示字体非紧凑。 */
    FULL_DESCRIPTOR_ATTR_B_MONO = 8,
    /** 字体是否支持符号字体，bool类型。true表示支持符号字体，false表示不支持符号字体。 */
    FULL_DESCRIPTOR_ATTR_B_SYMBOLIC = 9,
} OH_Drawing_FontFullDescriptorAttributeId;

/**
 * @brief 获取与指定字体描述符匹配的所有系统字体描述符，其中{@link OH_Drawing_FontDescriptor}的path字段不作为有效的匹配字段，其余字段不是默认值时生效。\n
 * 如果参数desc的所有字段都是默认值，则获取所有系统字体描述符。\n
 * 如果匹配失败，返回NULL。不再需要{@link OH_Drawing_FontDescriptor}时，请使用{@link OH_Drawing_DestroyFontDescriptors}接口释放该对象的指针。
 *
 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing
 * @param desc {@link OH_Drawing_FontDescriptor}指针。\n
 * 建议使用{@link OH_Drawing_CreateFontDescriptor}获得有效的{@link OH_Drawing_FontDescriptor}实例。\n
 * 如果自己创建{@link OH_Drawing_FontDescriptor}实例，请确保不用于匹配的字段是默认值。
 * @param num 表示返回值数组的成员个数。
 * @return {@link OH_Drawing_FontDescriptor}数组，释放时请使用{@link OH_Drawing_DestroyFontDescriptors}。
 * @since 18
 * @version 1.0
 */
OH_Drawing_FontDescriptor* OH_Drawing_MatchFontDescriptors(OH_Drawing_FontDescriptor* desc, size_t* num);

/**
 * @brief 释放字体描述符{@link OH_Drawing_FontDescriptor}数组。
 *
 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing
 * @param descriptors {@link OH_Drawing_FontDescriptor}数组。
 * @param num {@link OH_Drawing_FontDescriptor}数组的成员个数。
 * @since 18
 * @version 1.0
 */
void OH_Drawing_DestroyFontDescriptors(OH_Drawing_FontDescriptor* descriptors, size_t num);

/**
 * @brief 根据字体名称和字体类型获取指定的字体描述符，支持系统字体、风格字体和用户已安装字体。\n
 * 字体描述符是描述字体特征的一种数据结构，它包含了定义字体外观和属性的详细信息。
 *
 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing
 * @param fullName 表示指向字体名称字符串{@link OH_Drawing_String}的指针。
 * @param fontType 表示字体类型的枚举值{@link OH_Drawing_SystemFontType}。
 * @return 指向字体描述符对象{@link OH_Drawing_FontDescriptor}的指针，不再需要{@link OH_Drawing_FontDescriptor}时，请使用{@link OH_Drawing_DestroyFontDescriptor}接口释放该对象的指针。
 * @since 14
 */
OH_Drawing_FontDescriptor* OH_Drawing_GetFontDescriptorByFullName(const OH_Drawing_String* fullName,
    OH_Drawing_SystemFontType fontType);

/**
 * @brief 根据字体类型获取对应字体的字体名称数组。
 *
 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing
 * @param fontType 表示字体类型的枚举值{@link OH_Drawing_SystemFontType}。
 * @return 返回对应字体类型的字体名称数组{@link OH_Drawing_Array}的指针，不再需要{@link OH_Drawing_Array}时，请使用{@link OH_Drawing_DestroySystemFontFullNames}接口释放该对象的指针。
 * @since 14
 */
OH_Drawing_Array* OH_Drawing_GetSystemFontFullNamesByType(OH_Drawing_SystemFontType fontType);

/**
 * @brief 在字体名称数组中通过索引获取对应位置的字体名称。
 *
 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing
 * @param fullNameArray 表示字体名称数组{@link OH_Drawing_Array}的指针。
 * @param index 数组的索引。
 * @return 返回对应索引的字体名称{@link OH_Drawing_String}的指针。
 * @since 14
 */
const OH_Drawing_String* OH_Drawing_GetSystemFontFullNameByIndex(OH_Drawing_Array* fullNameArray, size_t index);

/**
 * @brief 释放通过字体类型获取的对应字体的字体名称数组占用的内存。
 *
 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing
 * @param fullNameArray 表示字体名称数组{@link OH_Drawing_Array}的指针。
 * @since 14
 */
void OH_Drawing_DestroySystemFontFullNames(OH_Drawing_Array* fullNameArray);

/**
 * @brief 根据原始二进制数据获取字体描述符数组。
 *
 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing
 * @param data 指向原始二进制字体数据缓冲区的指针。
 * @param size 以字节为单位的字体数据缓冲区的大小。
 * @return 返回指向对应字体文件的字体描述符数组{@link OH_Drawing_Array}的指针，不再需要OH_Drawing_Array时，请使用{@link OH_Drawing_DestroyFontFullDescriptors}接口释放该对象的指针。\n
 * 如果因数据格式无效或解析错误导致操作失败，返回NULL。
 * @since 22
 */
OH_Drawing_Array* OH_Drawing_GetFontFullDescriptorsFromStream(const void* data, size_t size);

/**
 * @brief 根据字体文件路径获取字体描述符数组。
 *
 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing
 * @param path 需要查询的字体文件的路径。
 * @return 返回指向对应字体文件的字体描述符数组{@link OH_Drawing_Array}的指针，不再需要OH_Drawing_Array时，请使用{@link OH_Drawing_DestroyFontFullDescriptors}接口释放该对象的指针。\n
 * 如果字体文件未找到、字体文件路径无效、字体文件无权限或者文件非字体格式，返回NULL。
 * @since 22
 */
OH_Drawing_Array* OH_Drawing_GetFontFullDescriptorsFromPath(const char* path);

/**
 * @brief 在字体描述符数组中通过索引获取对应的字体描述符。
 *
 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing
 * @param descriptorArray 表示指向字体描述符数组{@link OH_Drawing_Array}的指针。
 * @param index 数组的索引，索引值从0开始。
 * @return 返回指向指定索引处字体描述符对象{@link OH_Drawing_FontFullDescriptor}的指针。\n
 * 如果索引超出范围或数组无效，则返回NULL。
 * @since 22
 */
const OH_Drawing_FontFullDescriptor* OH_Drawing_GetFontFullDescriptorByIndex(
    OH_Drawing_Array* descriptorArray, size_t index);

/**
 * @brief 释放字体描述符数组占用的内存。
 *
 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing
 * @param descriptorArray 表示指向字体描述符数组{@link OH_Drawing_Array}的指针。
 * @since 22
 */
void OH_Drawing_DestroyFontFullDescriptors(OH_Drawing_Array* descriptorArray);

/**
 * @brief 获取int类型字体描述符的属性。
 *
 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing
 * @param descriptor 指向字体描述符对象{@link OH_Drawing_FontFullDescriptor}的指针。
 * @param id 字体描述符属性id。从{@link OH_Drawing_FontFullDescriptorAttributeId}中可获取字体描述符属性。
 * @param value 指向int类型属性的指针。作为出参使用。
 * @return 函数执行结果。\n
 * 返回OH_DRAWING_SUCCESS，表示执行成功。\n
 * 返回OH_DRAWING_ERROR_INCORRECT_PARAMETER，表示参数descriptor或者value为空指针。\n
 * 返回OH_DRAWING_ERROR_ATTRIBUTE_ID_MISMATCH，表示传入属性id与调用函数不匹配。
 * @since 22
 */
OH_Drawing_ErrorCode OH_Drawing_GetFontFullDescriptorAttributeInt(const OH_Drawing_FontFullDescriptor* descriptor,
    OH_Drawing_FontFullDescriptorAttributeId id, int* value);

/**
 * @brief 获取bool类型字体描述符的属性。
 *
 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing
 * @param descriptor 指向字体描述符对象{@link OH_Drawing_FontFullDescriptor}的指针。
 * @param id 字体描述符属性id。从{@link OH_Drawing_FontFullDescriptorAttributeId}中可获取字体描述符属性。
 * @param value 指向bool类型属性的指针。作为出参使用。
 * @return 函数执行结果。\n
 * 返回OH_DRAWING_SUCCESS，表示执行成功。\n
 * 返回OH_DRAWING_ERROR_INCORRECT_PARAMETER，表示参数descriptor或者value为空指针。\n
 * 返回OH_DRAWING_ERROR_ATTRIBUTE_ID_MISMATCH，表示传入属性id与调用函数不匹配。
 * @since 22
 */
OH_Drawing_ErrorCode OH_Drawing_GetFontFullDescriptorAttributeBool(const OH_Drawing_FontFullDescriptor* descriptor,
    OH_Drawing_FontFullDescriptorAttributeId id, bool* value);

/**
 * @brief 获取{@link OH_Drawing_String}类型字体描述符的属性。
 *
 * @note 如果不再需要OH_Drawing_String时，调用方需要手动释放OH_Drawing_String结构体内部的strData成员。
 *
 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing
 * @param descriptor 指向字体描述符对象{@link OH_Drawing_FontFullDescriptor}的指针。
 * @param id 字体描述符属性id。从{@link OH_Drawing_FontFullDescriptorAttributeId}中可获取字体描述符属性。
 * @param str 指向OH_Drawing_String类型属性的指针。作为出参使用。
 * @return 函数执行结果。\n
 * 返回OH_DRAWING_SUCCESS，表示执行成功。\n
 * 返回OH_DRAWING_ERROR_INCORRECT_PARAMETER，表示参数descriptor或者str为空指针。\n
 * 返回OH_DRAWING_ERROR_ATTRIBUTE_ID_MISMATCH，表示传入属性id与调用函数不匹配。
 * @since 22
 */
OH_Drawing_ErrorCode OH_Drawing_GetFontFullDescriptorAttributeString(const OH_Drawing_FontFullDescriptor* descriptor,
    OH_Drawing_FontFullDescriptorAttributeId id, OH_Drawing_String* str);

#ifdef __cplusplus
}
#endif
/** @} */
#endif